Skip to content

DOCS-1823 - Align Claude Code tooling with /docs/contributing - #7069

Merged
kimsauce merged 13 commits into
mainfrom
DOCS-1823
Sep 1, 2026
Merged

DOCS-1823 - Align Claude Code tooling with /docs/contributing#7069
kimsauce merged 13 commits into
mainfrom
DOCS-1823

Conversation

@kimsauce

@kimsauce kimsauce commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator

Purpose of this pull request

Aligns AGENTS.md, README, and the contributing guide on what Claude Code tooling is available to external vs. internal contributors, then expands into a full proofread, consolidation, and restructuring pass across docs/contributing/: style-guide fixes, terminology consistency, deduplicated content, a new Docs Templates hub page, and a top-nav entry.

See the commit history for the itemized breakdown.

A related but separate change (moving the back-end merge window from 7am to 6am PT) was split out into #7076 / DOCS-1840.

Select the type of change

  • Minor Changes - Typos, formatting, slight revisions
  • Update Content - Revisions, updating sections
  • New Content - New features, sections, pages, tutorials
  • Site and Tools - .clabot, version updates, maintenance, dependencies, new packages for the site (Docusaurus, Gatsby, React, etc.)

Ticket (if applicable)

https://sumologic.atlassian.net/browse/DOCS-1823

🤖 Generated with Claude Code

…and contributing guide

- AGENTS.md: clarify the repo takes both internal and external
  contributions; mark Jira Rules and Jira Commands sections as
  Sumo Logic internal (requires Atlassian access)
- README.md: rename "For Docs Team contributors" to "Claude Code
  tooling" and correct scope — most slash commands work for anyone
  with the repo cloned, only Jira commands are internal-only
- docs/contributing/create-edit-doc.md: note that /doc, /audit-doc,
  and /seo-audit are available to external contributors
- docs/contributing/remove-doc.md: note that /remove-doc automates
  this page's steps
- docs/contributing/style-guide.md: note that the sumo-style skill
  auto-applies these conventions in Claude Code, no invocation needed

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce kimsauce self-assigned this Aug 26, 2026
@cla-bot cla-bot Bot added the cla-signed Contributor approved, listed in .clabot file label Aug 26, 2026
@kimsauce
kimsauce marked this pull request as draft August 26, 2026 12:59
@kimsauce
kimsauce marked this pull request as ready for review August 31, 2026 19:33
Content fixes across README.md and the contributing docs:
- Fix ~20 style-guide violations: em dashes, uncommon contractions,
  missing terminal periods, Markdown capitalization, mislabeled code
  fence languages, an outdated tool recommendation (Atom)
- Tighten wordy/awkward phrasing (CID explanation, minor-fix intro,
  commit-message instructions); fix "Doc Team"->"Docs Team" and
  "content ID" capitalization inconsistencies
- Rewrite the docs/contributing landing page intro: cut generic
  corporate boilerplate that didn't describe this repo, and fix a
  code-vs-docs terminology mismatch ("fixing bugs, adding features"
  on a docs-only repo)
- Add missing card descriptions to the six docs/contributing hub cards
- Apply "Pull Request (PR)" first-reference-then-acronym consistently
  across README and the contributing docs

Structural consolidation:
- Extract the repeated fork/branch/GitHub-tips instructions into a
  shared reuse/contributing/fork-repo.md partial, used by both the
  "Edit a doc" and "Create a new doc" flows
- Move doc-prerequisites.md into reuse/contributing/ and fold the
  VS Code tooling recommendation into it (replacing the now-deleted
  reuse/contributing/tools.md)
- Fix a broken <Tools/> reference and a stale import path left over
  from the moves above
- Trim the "Using Claude Code" tips on create-edit-doc.md and
  remove-doc.md to point at README's policy instead of restating it;
  restore remove-doc.md's page-specific /remove-doc callout after it
  was accidentally overwritten with generic text
- Retitle all "Using Claude Code" tips to "Recommended: Use Claude
  Code"; add a noindex tag and fix a missing verb in the equivalent
  tips on the app-template-v2, c2c-source, and generic-doc templates
- Simplify partner-app-doc.md to defer to app-template-v2.md and
  append only its unique Support section, instead of maintaining a
  separately drifted copy; add a note pointing out that most partner
  apps are documented on the partner's own site or in the separate
  sumologic-public-partner-apps repo, not as a page on this site

New:
- Add docs/contributing/templates/index.md, a hub page for the four
  doc templates, with a tip pointing to the equivalent Claude Code
  slash commands (/doc, /app-doc, /c2c-source-doc, /release-note-*)
  as a faster alternative to copying a template by hand
- Wire the Docs Templates sidebar category to the new hub page

Navigation:
- Add a "Contribute to Docs" entry to the top-nav Guides dropdown,
  matching the existing Support entry

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce kimsauce changed the title DOCS-1823 - Align Claude Code tooling docs across AGENTS.md, README, and contributing guide DOCS-1823 - Align Claude Code tooling docs and overhaul the contributing guide Aug 31, 2026
kimsauce and others added 3 commits August 31, 2026 17:52
…plates hub page

The CID redirect from /docs/contributing/templates to
/docs/contributing/templates/generic-doc predates
docs/contributing/templates/index.md (added earlier in this branch).
Now that a real page lives at that URL, the redirect plugin fails
the production build: "The redirect plugin is not supposed to
override existing files." Removing the now-obsolete redirect; the
URL resolves to the real hub page instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce kimsauce changed the title DOCS-1823 - Align Claude Code tooling docs and overhaul the contributing guide DOCS-1823 - Align Claude Code tooling with /docs/contributing Sep 1, 2026
Comment thread docs/contributing/index.md Outdated
Comment thread docs/contributing/index.md Outdated
amee-sumo and others added 2 commits September 1, 2026 13:59
Co-authored-by: Kim (Sumo Logic) <56411016+kimsauce@users.noreply.github.com>
Co-authored-by: Kim (Sumo Logic) <56411016+kimsauce@users.noreply.github.com>

@amee-sumo amee-sumo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the full diff — no blocking issues. Verified:

  • No dangling references to the two deleted reuse fragments (docs/reuse/contributing/tools.md, docs/reuse/doc-prerequisites.md).
  • partner-app-doc.md's 102-line cut is legitimate dedup — the content still lives in app-template-v2.md.
  • sidebars.ts/docusaurus.config.js changes correctly wire up the new nav entry and Templates hub category.
  • cid-redirects.json's removed entry was safe (the path is now the real hub page).
  • No leaked content from the split-out merge-window PR (#7076/DOCS-1840).

One small non-blocking follow-up: docs/contributing/index.md (the "Contribute to Sumo Docs" landing page) wasn't updated with a card/link to the new Docs Templates hub page (docs/contributing/templates/index.md), even though it's now surfaced in the top nav and sidebar. Worth a quick follow-up for discoverability.

@JV0812

JV0812 commented Sep 1, 2026

Copy link
Copy Markdown
Collaborator

Reviewed the full diff and checked out the branch to run a from-scratch yarn build — no broken links/anchors, and the new docs/contributing/templates/index.md sidebar link (id: 'contributing/templates/index') is correct (matches the existing api/index precedent for index.md docs without an explicit id). The docusaurus.config.js fix (was .ts, actual file is .js) in the README is also a legitimate correction.

One real bug: this PR adds a second "Contribute to Docs" entry to the top nav, in the Guides dropdown (right after "Traces, RUM, APM"). That label already exists in the Support dropdown (Contact Support / Request a Demo / Submit Feedback / Contribute to Docs), added by #7031 which merged separately. After this merges, the nav will show "Contribute to Docs" twice, in two different dropdowns — worth fixing (either drop the new one since Support already covers it, or drop the old one if Guides is the better home) before/soon after merge.

@JV0812 JV0812 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified via a full local build (no broken links/anchors) and spot-checked the structural changes (new templates hub page, sidebar link, redirect removal, config filename fix). Left a comment flagging a duplicate 'Contribute to Docs' navbar entry — worth a quick fix but not blocking.

kimsauce and others added 3 commits September 1, 2026 03:22
- Add a Docs Templates card to the contributing hub page (index.md) so the
  new templates hub is discoverable from the landing page, not just nav.
- Remove the duplicate "Contribute to Docs" navbar entry from the Support
  dropdown; keep the new one in the Guides dropdown.
- Move contributing/code-of-conduct after the Docs Templates category in
  sidebars.ts so the sidebar order matches the hub page card order.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The Move or Remove a Doc guide walked through editing files but never told
contributors to fork the repo or open a pull request. Add Fork, Preview,
and Submit steps (reusing the shared contributing fragments), reword the
final step to test the redirect after the PR is merged and deployed, and
add a "What happens next?" section to match create-edit-doc.md.

Renumbering the redirect step also required updating the inbound anchor
link in style-guide.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce
kimsauce enabled auto-merge September 1, 2026 10:24
@kimsauce
kimsauce added this pull request to the merge queue Sep 1, 2026
Merged via the queue into main with commit 2e8e300 Sep 1, 2026
3 of 4 checks passed
@kimsauce
kimsauce deleted the DOCS-1823 branch September 1, 2026 10:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla-signed Contributor approved, listed in .clabot file

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants